03 通义千问 API 调用基础实现

通义千问 API 调用基础实现

关联：索引

AI 工具使用：API 调用与调参提示词模板（学生可直接复制）

使用方法：把你自己的代码/报错/实验记录粘贴到 {你的内容} 处；要求 AI 输出结构化结果（表格/步骤/清单），便于你照做与复盘。

模板 1：生成最小可运行调用代码
模板 2：参数对比实验设计
模板 3：报错排查（定位→修复→预防）
模板 4：代码结构与规范优化

模板 1：生成最小可运行调用代码（文本生成 + 问答）

你是 Python 实践课助教。请给我一份“最小可运行”的通义千问调用示例代码，要求：
1）使用 dashscope SDK；API Key 从环境变量 DASHSCOPE_API_KEY 读取；
2）包含两个函数：generate_text(prompt)、answer_question(question)；
3）将 temperature、top_p、max_length（输出长度上限）作为可配置参数；
4）对常见失败进行处理：Key 缺失、参数非法、频率超限（给出可执行的排查提示）；
5）输出内容要清晰：打印 request_id、模型名、最终文本结果。

我当前环境/需求：{你的内容}

模板 2：参数对比实验设计（温度 vs top_p）

请围绕“通义千问生成效果的可控性”，为我设计一个课堂参数对比实验：
1）给出 2 个固定 Prompt（一个偏事实问答、一个偏创意写作）；
2）给出 3 组参数组合（temperature、top_p、max_length），每组说明预期差异；
3）给出记录表模板：参数→输出特点→是否跑题→是否重复→可读性→结论。

补充要求：实验需要能在较短时间内完成。
我的笔记内容：{你的内容}

模板 3：报错排查（定位→修复→预防）

下面是我调用通义千问 API 的报错信息与代码片段。请你按“定位→修复→预防”的结构输出：
1）先判断属于哪类问题：密钥/权限、参数非法、频率超限、网络、代码逻辑；
2）给出最短排查步骤（最多 6 步），每一步要具体到我该检查什么；
3）给出修复后的代码改动建议（用要点，不要长篇解释）；
4）给出预防清单（3 条以内）。

我的内容：{你的内容}

模板 4：代码结构与规范优化（把脚本变成可复用工具）

请帮我把下面这段通义千问调用脚本优化成“可复用的工程化结构”，要求：
1）用函数拆分：读取配置、调用模型、解析输出、打印结果；
2）加入基本的参数校验与异常提示（不要引入复杂第三方库）；
3）保持代码短小、便于课堂演示（不超过 120 行）。

我的代码：{你的内容}

1. 接入流程（从 0 到 1）

注册开发者平台账号（实名/额度/开通服务按平台要求完成）。
创建 API Key（用于身份认证）。
在本机安全配置 Key（推荐环境变量或 .env，避免写进代码）。
用最小脚本发起一次请求并拿到有效返回。
不要把 Key 写进代码仓库/群聊/截图；投影演示时务必打码。
不要把 Key 作为字符串硬编码在 .py 文件里。
推荐使用环境变量：DASHSCOPE_API_KEY；或用 .env 配合 python-dotenv 读取。

前提：已在上一节课安装 dashscope==1.25.13 和 python-dotenv==1.2.2。

1. 配置 Key（两种方式二选一）

方式 A：环境变量（推荐）

# Windows PowerShell（临时，仅当前终端生效）
$env:DASHSCOPE_API_KEY="你的Key"

# Windows PowerShell（永久，重开终端后生效）
setx DASHSCOPE_API_KEY "你的Key"

验证（不会泄露完整 Key）：

python -c "import os; k=os.getenv('DASHSCOPE_API_KEY'); print('未配置DASHSCOPE_API_KEY' if not k else (k[:3]+'***'+k[-3:]))"

在项目根目录新建 .env（不要提交到仓库）：

DASHSCOPE_API_KEY=你的Key

然后在 Python 里加载：

from dotenv import load_dotenv
load_dotenv()

2. 文本生成（最小调用）

import os
from http import HTTPStatus

import dashscope
from dashscope import Generation

dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

def generate_text(prompt: str, temperature: float = 0.7, top_p: float = 0.8, max_length: int = 256) -> str:
    if not dashscope.api_key:
        raise RuntimeError("未配置 DASHSCOPE_API_KEY：请先设置环境变量或使用 .env 加载")
    resp = Generation.call(
        model=Generation.Models.qwen_turbo,
        prompt=prompt,
        temperature=temperature,
        top_p=top_p,
        max_length=max_length,
    )
    if resp.status_code != HTTPStatus.OK:
        raise RuntimeError(f"调用失败: status_code={resp.status_code}, code={resp.code}, message={resp.message}, request_id={resp.request_id}")
    print(f"model={Generation.Models.qwen_turbo}, request_id={resp.request_id}")
    return resp.output.get("text", "")

def answer_question(question: str, temperature: float = 0.3, top_p: float = 0.8, max_length: int = 256) -> str:
    return generate_text(f"请用3点回答：{question}", temperature=temperature, top_p=top_p, max_length=max_length)

if __name__ == "__main__":
    print(generate_text("用一句话解释什么是 API。"))
    print(answer_question("温度 temperature 参数一般调大有什么效果？"))

成功标志：终端能打印出一段非空文本结果；若失败，能看到明确的 status_code / code / message / request_id。

3. 问答（用同一接口实现）

question = "温度 temperature 参数一般调大有什么效果？"
print(generate_text(f"请用3点回答：{question}", temperature=0.3, top_p=0.8, max_length=256))

用同一个 Prompt，做两次调用对比：

组合 A：temperature=0.2, top_p=0.8
组合 B：temperature=0.9, top_p=0.95

记录：是否更发散、是否更有创意、是否更容易跑题、是否更重复。

快速回顾：Key 推荐放哪里？（环境变量/.env）为什么不写在代码里？
快速回顾：调用失败看哪四个字段？（status_code / code / message / request_id）

目标：记住“参数影响的现象”，而不是背定义。

参数	你能观察到的现象	常见建议
temperature	值越大越发散、越有创意，但更可能跑题（通常为 0~2 的小数）	问答/抽取偏低；创作偏高
top_p	控制从“概率质量”里采样的范围，越大越开放（通常为 0~1 的小数）	与 temperature 搭配使用
max_length / max_tokens	输出长度上限，太小会截断（正整数）	先保守给足，再逐步收敛

参数命名说明（SDK vs 控制台/HTTP）

DashScope Python SDK 的 Generation.call(...) 常用参数名是 temperature / top_p / max_length。
百炼控制台与 HTTP API 文档中，输出长度上限常见参数名为 max_tokens，语义与 max_length 对齐。
输入方式也常见两种：
messages=[...] 且 result_format='message'：更接近控制台/HTTP API 的请求结构。

1. 密钥错误（Key 缺失/无效/权限不足）

排查顺序：

print(os.getenv("DASHSCOPE_API_KEY")) 是否为 None/空字符串？
Key 是否复制错误（多空格/少字符）？
是否在新终端里运行（环境变量未刷新）？

2. 参数非法（类型不对/范围不对/字段名不对）

排查顺序：

先把参数减少到最少：只传 model + prompt 能否成功？
再逐个加回 temperature/top_p/max_length，定位是哪一个触发报错。

3. 请求频率超限（限流/并发过高）

排查顺序：

是否在循环里高频调用、或多人共用一个 Key？

目标：让 AI 变成“更快写出可运行脚本 + 更快定位报错”的工具，而不是替你写完全部作业。

用模板 1：让 AI 生成最小可运行代码（你对照自己的代码挑差异点）。
用模板 3：把你的报错 + 代码片段粘给 AI，让它按“定位→修复→预防”输出排查步骤。

一个 qwen_call.py 脚本（文本生成 + 问答两种调用都能跑通）
记录一个报错与修复过程（可人为制造：把 Key 改错 1 位再修复）

作业（课后完成）

提交 API 调用代码（文本生成 + 问答功能），要求包含参数配置注释（写清 temperature/top_p/max_length 的意义与取值）。
提交 API 调用成功的运行截图（含终端输出/返回结果，注意 Key 打码）。
记录至少 2 个不同参数组合的测试结果，分析参数对生成效果的影响（150 字左右）。